{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# XML Summary\n",
    "This part summerizes key elements in a Mujoco XML model that is important for rigid-body robotic systems. Complete and detailed information can be found in the official website \n",
    "https://mujoco.readthedocs.io/en/latest/XMLreference.html\n",
    "\n",
    "\n",
    "\n",
    "## Frame orientation:\n",
    "\n",
    "The frame orientation is specified using at most one of these attributes. The quat attribute has a default value corresponding to the null rotation, while the others are initialized in the special undefined state. Thus if none of these attributes are specified by the user, the frame is not rotated.\n",
    "\n",
    "- quat: real(4), “1 0 0 0”\n",
    "  If the quaternion is known, this is the preferred was to specify the frame orientation because it does not involve conversions. Instead it is normalized to unit length and copied into mjModel during compilation. When a model is saved as MJCF, all frame orientations are expressed as quaternions using this attribute.\n",
    "\n",
    "- axisangle: real(4), optional\n",
    "  These are the quantities (x,y,z,a) mentioned above. The last number is the angle of rotation, in degrees or radians as specified by the angle attribute of compiler. The first three numbers determine a 3D vector which is the rotation axis. This vector is normalized to unit length during compilation, so the user can specify a vector of any non-zero length. Keep in mind that the rotation is right-handed; if the direction of the vector (x,y,z) is reversed this will result in the opposite rotation. Changing the sign of a can also be used to specify the opposite rotation.\n",
    "\n",
    "- euler: real(3), optional\n",
    "  Rotation angles around three coordinate axes. The sequence of axes around which these rotations are applied is determined by the eulerseq attribute of compiler and is the same for the entire model.\n",
    "\n",
    "- xyaxes: real(6), optional\n",
    "  The first 3 numbers are the X axis of the frame. The next 3 numbers are the Y axis of the frame, which is automatically made orthogonal to the X axis. The Z axis is then defined as the cross-product of the X and Y axes.\n",
    "\n",
    "- zaxis: real(3), optional\n",
    "  The Z axis of the frame. The compiler finds the minimal rotation that maps the vector (0,0,1) into the vector specified here. This determines the X and Y axes of the frame implicitly. This is useful for geoms with rotational symmetry around the Z axis, as well as lights – which are oriented along the Z axis of their frame.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## body\n",
    "- need to specify: name (optional)\n",
    "- pos, orientation (see frame orientation section) relative to parant coordinate system\n",
    "- and important sub-element (geom, inertia, joint, etc)\n",
    "\n",
    "### body/inertial:\n",
    "- This element specifies the mass and inertial properties of the body. If this element is not included in a given body, the inertial properties are inferred from the geoms attached to the body. When a compiled MJCF model is saved, the XML writer saves the inertial properties explicitly using this element, even if they were inferred from geoms. The inertial frame is such that its center coincides with the center of mass of the body, and its axes coincide with the principal axes of inertia of the body. Thus the inertia matrix is diagonal in this frame.\n",
    "- *pos*: position of inertial frame. \n",
    "- *orientation*: of the inertial frame\n",
    "- *mass*: positive number required\n",
    "- *diaginertia* (real(3)): diagonal entries of the inertial matrix;\n",
    "- *fullinertia*: real(6): Full inertia matrix M. Since M is 3-by-3 and symmetric, it is specified using only 6 numbers in the following order: M(1,1), M(2,2), M(3,3), M(1,2), M(1,3), M(2,3). \n",
    "\n",
    "### body/joint\n",
    "A joint creates motion degrees of freedom between the body where it is defined and the body’s parent. If no joints are defined, the body is welded to its parent. Joints cannot be defined in the world body. At runtime the positions and orientations of all joints defined in the model are stored in the vector mjData.qpos, in the order in which they appear in the kinematic tree. The linear and angular velocities are stored in the vector mjData.qvel. These two vectors have different dimensionality when free or ball joints are used, because such joints represent rotations as unit quaternions.\n",
    "  - **name**, **class**: optional \n",
    "  - **type**: \n",
    "    - *free*: 6Dof joint. This joint type is only allowed in bodies that are children of the world body. Free joints do not have a position within the body frame. Instead the joint position is assumed to coincide with the center of the body frame. Thus at runtime the position and orientation data of the free joint correspond to the global position and orientation of the body frame. Free joints cannot have limits.\n",
    "    - *slide*: a sliding or prismatic joint with one translational degree of freedom. Such joints are defined by a position and a sliding direction. For simulation purposes only the direction is needed; the joint position is used for rendering purposes.\n",
    "    - *hinge*: The rotation takes place around a specified axis through a specified position. This is the most common type of joint and is therefore the default. \n",
    "  - **pos**: Position of the joint, specified in the frame of the body where the joint is defined. For free joints this attribute is ignored.\n",
    "  - **axis**: This attribute specifies the axis of rotation for hinge joints and the direction of translation for slide joints.\n",
    "\n",
    "### body/geom\n",
    "- need to specify: name (optional), class (optional), pos, orientation (see frame orientation section), type, size (different meanings for different types), material (reference to materials defined in assets), rgba, among others. \n",
    "  \n",
    "- **type**: (default: \"sphere\")\n",
    "  - \"box\": The box type defines a box. Three size parameters are required, corresponding to the half-sizes of the box along the X, Y and Z axes of the geom’s frame. \n",
    "  - \"cylinder\": defines a cylinder, which requires two size parameters: the radius and half-height of the cylinder. The cylinder is oriented along the Z axis of the geom’s frame. \n",
    "  - \"mesh\": defines a mesh. The geom must reference the desired mesh asset with the mesh attribute. Note that mesh assets can also be referenced from other geom types, causing primitive shapes to be fitted; see below. The size is determined by the mesh asset and the geom size parameters are ignored.\n",
    "- **fromto**: This attribute can only be used with capsule, box, cylinder and ellipsoid geoms. It provides an alternative specification of the geom length as well as the frame position and orientation. The six numbers are the 3D coordinates of one point followed by the 3D coordinates of another point. \n",
    "- **pos**: (x,y,z) position \n",
    "- orietation related: see frame orietation section\n",
    "- **material**: \n",
    "- **rgba**: \n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## asset\n",
    "Assets are not in themselves model elements. Model elements can reference them, in which case the asset somehow changes the properties of the referencing element. One asset can be referenced by multiple model elements. Since the sole purpose of including an asset is to reference it, and referencing can only be done by name, every asset has a name (which may be inferred from a file name when applicable).\n",
    "\n",
    "### asset/mesh\n",
    "MuJoCo works with triangulated meshes. They can be loaded from binary STL files, OBJ files or MSH files. \n",
    "\n",
    "### asset/material\n",
    "It can be referenced from skins, geoms, sites and tendons to set their appearance. Materials are useful for adjusting appearance properties beyond color."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## actuator\n",
    "MuJoCo provides a flexible actuator model. All actuators are single-input-single-output (SISO). \n",
    "- The input to actuator $i$ a scalar control $u_i$ specified by the user. \n",
    "- The output is a scalar force $p_i$, which is mapped to joint coordinates by a vector of moment arms determined by the transmission. \n",
    "- An actuator can also have activation state $w_i$ with its own dynamics\n",
    "- The control inputs for all actuators are stored in mjData.ctrl, the force outputs are stored in mjData.actuator_force, and the activation states (if any) are stored in mjData.act.\n",
    "  \n",
    "### actuator/general:\n",
    "- joint/site: either specify a joint or a site for applying the force. \n",
    "- dyntype (\"none\"): internal dynamics type, including integrator, filter, filerexact, muscle, user... . The last case with \"user\" allows customize callback functions for actuator dynamics. \n",
    "- gaintype: The gain and bias together determine the output of the force generation mechanism, which is currently assumed to be affine. The general formula is: \n",
    "      **scalar_force = gain_term * (act or ctrl) + bias_term**\n",
    "- ctrllimited: If true, the control input to this actuator is automatically clamped to ctrlrange at runtime\n",
    "- forcelimited: If true, the force output of this actuator is automatically clamped to forcerange at runtime\n",
    "\n",
    "### pre-defined actuator options: \n",
    "Below are actuator shortcuts discussed earlier. When a such shortcut is encountered, the parser creates a general actuator and sets its dynprm, gainprm and biasprm attributes to the internal defaults shown above, regardless of any default settings.\n",
    "\n",
    "- actuator/motor: \n",
    "\n",
    "| Attribute   | Setting       | Attribute   | Setting       |\n",
    "|-------------|---------------|-------------|---------------|\n",
    "| dyntype     | none          | gaintype    | fixed         |\n",
    "| dynprm      | 1 0 0        | gainprm     | 1 0 0        |\n",
    "| biastype     | none          | biasprm     | 0 0 0        |\n",
    "\n",
    "- actuator/position:\n",
    "  This element creates a position servo with an optional first-order filter. The underlying general attributes are set as follows: \n",
    "\n",
    "| Attribute   | Setting                  | Attribute   | Setting            |\n",
    "|-------------|--------------------------|-------------|---------------------|\n",
    "| dyntype     | none or filterexact      | gaintype    | fixed               |\n",
    "| dynprm      | timeconst 0 0            | gainprm     | kp 0 0              |\n",
    "| biastype     | affine                  | biasprm     | 0 -kp -kv           |\n",
    "  \n",
    "- actuator/velocity\n",
    "  This element creates a velocity servo. Note that in order create a PD controller, one has to define two actuators: a position servo and a velocity servo. This is because MuJoCo actuators are SISO while a PD controller takes two control inputs (reference position and reference velocity). When using this actuator, it is recommended to use the implicitfast or implicit integrators. The underlying general attributes are set as follows:\n",
    "\n",
    "| Attribute   | Setting       | Attribute   | Setting        |\n",
    "|-------------|---------------|-------------|-----------------|\n",
    "| dyntype     | none          | gaintype    | fixed           |\n",
    "| dynprm      | 1 0 0        | gainprm     | kv 0 0          |\n",
    "| biastype     | affine        | biasprm     | 0 0 -kv         |\n",
    "\n",
    "- actuator/damper\n",
    "  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Sensor\n",
    "The outputs of all sensors are concatenated in the field mjData.sensordata which has size mjModel.nsensordata. This data is not used in any internal computations.\n",
    "\n",
    "- Sipmle example: \n",
    "  > <sensor>\n",
    "        <jointpos name=\"joint1_position_sensor\" joint=\"joint1\"/> \n",
    "        <jointvel name=\"joint1_velocity_sensor\" joint=\"joint1\"/> \n",
    "    </sensor>\n",
    "- other attributes:\n",
    "  - **force**: 3-axis force. The sensor outputs three numbers, which are the interaction force between a child and a parent body, expressed in the site frame defining the sensor. The convention is that the site is attached to the child body, and the force points from the child towards the parent.\n",
    "    - note that *site* sub-element is required. \n",
    "  - **torque**:  a 3-axis torque similar to force\n",
    "  - "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": []
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}
